/*
 * Copyright (C) 2012 "Lexaden.com"
 *     contact@lexaden.com [http://www.lexaden.com]
 *
 *     This file is part of Lexaden Administration.
 *
 *     Lexaden Administration is free software: you can redistribute it and/or modify
 *     it under the terms of the GNU Affero General Public License as
 *     published by the Free Software Foundation, either version 3 of the
 *     License, or (at your option) any later version.
 *
 *     This program is distributed in the hope that it will be useful,
 *     but WITHOUT ANY WARRANTY; without even the implied warranty of
 *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *     GNU Affero General Public License for more details.
 *
 *     You should have received a copy of the GNU Affero General Public License
 *     along with this program. If not, see <http://www.gnu.org/licenses/>.
 */

package com.navajo.web.spring;

import java.util.Locale;

/**
 * Strategy interface for resolving messages, with support for the parameterization
 * and internationalization of such messages.
 */
public interface MessageSource {
    /**
     * Try to resolve the message. Treat as an error if the message can't be found.
     *
     * @param key - the code to lookup up
     * @return the resolved message
     */
    public String getMessage(String key);

    /**
     * *
     * Try to resolve the message. Treat as an error if the message can't be found.
     *
     * @param key    the code to lookup up
     * @param locale the Locale in which to do the lookup
     * @return the resolved message
     */
    public String getMessage(String key, Locale locale);

    /**
     * Try to resolve the message. Treat as an error if the message can't be found.
     *
     * @param key  - the code to lookup up
     * @param args - array of arguments that will be filled in for params
     *             within the message
     * @return the resolved message
     */
    public String getMessage(String key, Object... args);

    /**
     * *
     * Try to resolve the message. Treat as an error if the message can't be found.
     *
     * @param key    - the code to lookup up
     * @param args   - Array of arguments that will be filled in for params within
     *               the message (params look like "{0}", "{1,date}", "{2,time}" within a message),
     *               or <code>null</code> if none.
     * @param locale - the Locale in which to do the lookup
     * @return the resolved message
     */
    public String getMessage(String key, Locale locale, Object... args);

    /**
     * Resolve the given key and arguments as message in the given Locale,
     * returning <code>null</code> if not found.
     *
     * @param key  - the code to lookup up
     * @param args - array of arguments that will be filled in for params
     *             within the message
     * @return the resolved message, or <code>null</code> if not found
     */
    public String getMessageOrNull(String key, Object... args);
}
